Crate maligned

Source
Expand description

A library for getting aligned vectors, slices, and arrays of bytes or any other type

The A* structs are aligned as indicated and hold a single array of bytes of the same size. These implement the Alignment trait that can be used for always aligned byte arrays for faster memory copies or copies by hardware. The arrays are accessible as slices using as_bytes() or as_bytes_mut() or by dereferencing the struct.

let alignment_256 = A256::default();

assert_eq!(std::mem::size_of::<A256>(), std::mem::size_of_val(alignment_256.as_bytes()));
assert_eq!(alignment_256.as_bytes().as_ptr() as usize % std::mem::size_of::<A256>(), 0);

If you need more than a single Alignment of bytes you can create a vector of them and that can be converted into a normal byte slice that always has the first byte aligned.

let mut v = vec![A512::default(); 100];
assert_eq!(v.as_bytes().len(), std::mem::size_of::<A512>() * 100);
assert_eq!(v.as_bytes().as_ptr() as usize % std::mem::align_of::<A512>(), 0);

v.as_bytes_mut()[512] = 42;
assert_eq!(v[1][0], 42);

There is also a wrapper Aligned that aligns any type to a specified alignment

// aligned() is an alias for Aligned::new()
let a: Aligned<A32, [u8; 24]> = aligned([0; 24]);
assert_eq!(std::mem::align_of_val(&a), 32);
assert_eq!(&*a as *const u8 as usize % std::mem::align_of::<A32>(), 0);

If the alloc feature is enabled (it is by default) then there are a few more functions available. align_first returns an empty Vec with a capacity of at least capacity bytes. Two type parameters are currently required, though the first can be set to _, because of the current interaction between impl traits and generics.

let v: Vec<u8> = align_first::<u8, A256>(1009);
assert_eq!(v.as_ptr() as usize % 256, 0);
assert_eq!(v.capacity(), 1009);

align_first_boxed, align_first_boxed_default, and align_first_boxed_cloned all return a Box<[T]> with the first element aligned to at least Alignment bytes.

// 3 type parameters. The last one should always be _ until impl traits and generics interact better
let boxed: Box<[Option<u128>]> = align_first_boxed::<_, A512, _>(101, |_|Some(42));
let defaulted: Box<[Option<u128>]> = align_first_boxed_default::<_, A128>(101);
let cloned: Box<[Option<u128>]> = align_first_boxed_cloned::<_, Bit512>(101, Some(42));

assert_eq!(&*boxed, &vec![Some(42); 101][..]);
assert_eq!(&boxed, &cloned);
assert_eq!(boxed.len(), 101);
assert_eq!(defaulted.len(), 101);
assert_eq!(cloned.len(), 101);
assert_eq!(&*defaulted, &vec![None; 101][..]);

Modules§

Structs§

  • A2
    Struct representing an alignment of 2
  • A4
    Struct representing an alignment of 4
  • A8
    Struct representing an alignment of 8
  • A16
    Struct representing an alignment of 16
  • A32
    Struct representing an alignment of 32
  • A64
    Struct representing an alignment of 64
  • A128
    Struct representing an alignment of 128
  • A256
    Struct representing an alignment of 256
  • A512
    Struct representing an alignment of 512
  • A1024
    Struct representing an alignment of 1024
  • A2048
    Struct representing an alignment of 2048
  • A4096
    Struct representing an alignment of 4096
  • A8192
    Struct representing an alignment of 8192
  • A16384
    Struct representing an alignment of 16384
  • A32768
    Struct representing an alignment of 32768
  • A65536
    Struct representing an alignment of 65536
  • A131072
    Struct representing an alignment of 131_072
  • Aligned
    Wrapper type that aligns T to at least Alignment It adds no size to the layout of the struct if the size is a multiple of the alignment, otherwise the size is rounded up to the next multiple of the alignment
  • FromByteSliceError
    Representation of failure to convert from a byte slice to some alignment type.

Traits§

  • Alignment
    Marker trait used for bounds. All structs that implement this trait have their size and alignment equal.
  • AsBytes
    Trait that allows reinterpretation of a struct as bytes. This is unsafe since the returned slice must always have a length equal to the size of the struct and because every bit pattern within the structs size must be valid.
  • AsBytesMut
    Trait that allows reinterpretation of a mutable struct as mutable bytes. This is unsafe since the returned slice must always have a length equal to the size of the struct and because every bit pattern within the structs size must be valid.

Functions§

  • align_first
    Aligns the first element in a Vec<T> to A. If the alignment of A is less than the alignment of T then a Vec<T> with capacity t_capacity is returned. This method is safe because structs are always aligned to a power of two so aligning the first item in a Vec<T> to a higher alignment will always be aligned correctly.
  • align_first_boxed
    Aligns types and initializes memory to the return value provided by the closure. Since boxed slices can never re-allocate the first item will always be aligned.
  • align_first_boxed_cloned
    Aligns types and initializes all values to clones of initial then returns a boxed slice. Since boxed slices can never re-allocate the first item will always be aligned.
  • align_first_boxed_default
    Aligns types and initializes memory to default then returns a boxed slice. Since boxed slices can never re-allocate the first item will always be aligned.
  • aligned
    Convenience function for creating a new Aligned Because of the current interaction between generics and impl arguments the function requires both types to be given, though the second one can be given the default _ To align a byte array to a 256 bit boundary

Type Aliases§